Overview

The steps described below are designed to allow you to quickly build RHQ in as few steps as possible. After you become more familiar with the code base and more proficient with the build system, you should check out our Advanced Build Notes for additional things you will find helpful in working with the RHQ Maven build system.

If you do not want to build RHQ from source, you can instead download a binary distribution.

If you want to get familiar with how each of the individual modules in the source tree contribute to the overall built product, please read the Module Overview.

Install JDK

1. Download the latest release of JDK 7 available for your OS from either Oracle here or OpenJDK and install it.

2. Set the following environment variables in your .profile (UNIX) or System environment (Windows) - you must ensure you set these if you have multiple Java installations on your box, to ensure Maven picks up the correct JDK that you want to use:

   • JAVA_HOME=JDK7_install_dir

   • PATH=$JAVA_HOME/bin:existing_PATH

Install Maven

1. Download the latest release of Maven 3.x from http://maven.apache.org/download.html.

2. Unzip it somewhere on your system (e.g. C:\opt, /opt/maven).

3. Set the following environment variables in your .profile (UNIX) or System environment (Windows):

   • MAVEN_HOME=maven_install_dir

   • MAVEN_OPTS="-Xms256M -Xmx768M -XX:PermSize=128M -XX:MaxPermSize=256M -XX:ReservedCodeCacheSize=96M"

   • PATH=$MAVEN_HOME/bin:existing_PATH

Install Git

Access to the git repository can be done via the git command line or via a plugin to your IDE.
To run git commands independently of your IDE, you can install git from http://git-scm.com/download.

• Eclipse - Eclipse now hosts the git plug-in which provides some of the git features. For info on the Eclipse git plug-in, see http://www.eclipse.org/egit/.

• IntelliJ IDEA - IntelliJ 9 and later has built-in support for git.

Install and Create Database for PostgreSQL

1. See the PostgreSQL Quick Start Installation Guide to install and configure PostgreSQL

2. Make sure to create the rhqadmin user and rhq database. Note: to ensure the initial mvn build below succeeds, you also need to have created a database called "rhqdev".

Checkout RHQ Sources

1. Open a command prompt and cd to the directory where you want the RHQ sources to live, e.g.:

   cd ~/projects

2. Clone the RHQ source from the git repo:

   git clone git://git.fedorahosted.org/git/rhq/rhq.git

   or if your firewall prevents using the git protocol you can also clone via http (much slower though)

   git clone http://git.fedorahosted.org/git/rhq/rhq.git

   or for developer access:

   Developer access

   git clone ssh://git.fedorahosted.org/git/rhq/rhq.git

   SSH properties

   Note: if your fedora user name is different from the local one or you have a different public key for
   fedora than some default one, you need to specify it to git/ssh.
   To do so you can add this to ~/.ssh/config:

   $ cat  ~/.ssh/config
   
   Host git.fedorahosted.org
   IdentityFile id_fedorahosted_rsa
   User joedev

   So in this example the fedora user is joedev and the ssh key is in ~/.ssh/id_fedorahosted_rsa

Build RHQ

1. Make sure you have set up the settings.xml file as described in Advanced Build Notes including uncommenting the postgres profile.

2. Make sure you have the Databases set up 

   createuser rhqadmin
   createdb -O rhqadmin rhq
   createdb -O rhqadmin rhqdev

3. Open a command prompt and cd to the directory where the RHQ sources live, e.g.:

   cd ~/projects/rhq

4. Build RHQ:

   mvn -Penterprise,dev -Ddbsetup -DskipTests install

   NOTES

   • The first time you build RHQ, it will take up to an hour, because it will need to download dozens of 3rd party dependency jars for both RHQ and Maven itself. Subsequent builds will be significantly faster, especially if you only build specific modules.

   • "-Ddbsetup" is only required the first time you build; thereafter, the schema will be created in your database, and you won't need to do it again unless a) the schema changes and needs to be rebuilt or b) you want to clean out your database and rebuild the schema

   • The RHQ BuildNumber is set to the git sha1.

   • If you have been building RHQ for a while and you notice that the versions of any dependencies in the dependencyManagement section of the root POM have changed due to a recent commit, you MUST build from root. If you don't, the {m2_repo}/org/rhq/rhq-parent/{currentVersion}/rhq-parent-{currentVersion}.pom file will be stale, and will be used when resolving dependencies locally, and thus you won't resolve to the latest dependencies. If you don't want to take the "hit" of building from root, you can build ONLY the root module by saying "mvn -N install" from the root, which will update the aforementioned POM in your local repository without building all modules.

   • If you run into test failures, run with the option -DskipTests so that those will be still built, but not executed. -Dmaven.test.skip will also skip building them and subsequent compilation will fail.

Run RHQ Server

1. First start the RHQ server, which is built to <rhq-root>/modules/enterprise/server/appserver/target/rhq-server-<version>:

   cd <rhq-root>/modules/enterprise/server/appservertarget/rhq-server-<version>/bin
   ./rhq-server.(sh|bat) console

   Because you built using the -Pdev Maven profile, you can also run the RHQ Server container that is built to <rhq-root>/dev-container. See Advanced Build Notes for more information on the enterprise and dev profiles

   Windows NOTE

   You may want to use the rhq-server-console.bat script - you can double click it to start the server. The rhq-server.bat expects a command line argument "console" so you cannot just double-click it from a Windows Explorer window to start it.

2. If you did not build with -Pdev, then once the RHQ server is fully started, complete the installation by running rhq-installer.(sh|bat) located in the same directory where the server startup script is found. If you did follow the instructions above (which included using -Pdev), the installer will run for you automatically when you start the server.

3. Point your browser to http://localhost:7080 and login as user rhqadmin, password rhqadmin.

Run a Local RHQ Agent

1. Next start the RHQ agent, which is built to <rhq-root>/modules/enterprise/agent/target/rhq-agent-<version>:

   cd <rhq-root>/modules/enterprise/agent/target/rhq-agent-<version>/bin
   ./rhq-agent.(sh|bat)

   The agent uses Java preferences which stores settings in the Windows registry (if on Windows) or $HOME/.java (if on UNIX). To purge the settings, run with the -L option.

2. Once the agent is fully started, a platform should appear in the autodiscovery UI page (under the main Inventory view); import this platform into RHQ's inventory.

IDE

If you want to contribute to RHQ, you can load the code base in your favorite Java IDE. We have some tips for the big two here:

• Eclipse

• IntelliJ IDEA